home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / il / ilError.z / ilError
Encoding:
Text File  |  2002-10-03  |  9.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. iiiillllEEEErrrrrrrroooorrrr((((3333))))         IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll         iiiillllEEEErrrrrrrroooorrrr((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      iiiillllEEEErrrrrrrroooorrrr,,,, iiiillllEEEErrrrrrrroooorrrrVVVV,,,, iiiillllGGGGeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr,,,, iiiillllSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr,,,,
  10.      iiiillllSSSSttttaaaattttuuuussssTTTTooooSSSSttttrrrriiiinnnngggg,,,, iiiillllMMMMaaaaiiiinnnnSSSSttttaaaattttuuuussssTTTTooooSSSSttttrrrriiiinnnngggg,,,, iiiillllSSSSttttaaaattttuuuussssFFFFrrrroooommmmIIIIffffllllSSSSttttaaaattttuuuussss,,,,
  11.      iiiillllSSSSttttaaaattttuuuussssEEEEnnnnccccooooddddeeee - error handling
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      #include <il/ilError.h>
  15.  
  16.      void ilError(int flags, const char* fmt, ...)
  17.      void ilErrorV(int flags, const char* fmt, va_list ap)
  18.  
  19.      void ilGetErrorHandler(ilErrorHandlerType* handler, void** arg)
  20.      void ilSetErrorHandler(ilErrorHandlerType newhandler, void* newarg)
  21.  
  22.      char* ilStatusToString(ilStatus status, char buf[], int bufsize)
  23.      const char* ilMainStatusToString(ilMainStatus status)
  24.      ilStatus ilStatusFromIflStatus(iflStatus iflstatus)
  25.      ilStatusEncode(unsigned int mainstatus,
  26.                     unsigned int subDomain = ilSubDomainNONE,
  27.                     unsigned int subStatus = 0)
  28.  
  29.  
  30. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  31.      These functions are used to report errors and control how those errors
  32.      are handled in the IL environment.  These facilities can also be used to
  33.      generate debugging messages.  The routines are grouped into three
  34.      functional areas: error reporting, error handling, and status code
  35.      translation.
  36.  
  37.    EEEErrrrrrrroooorrrr RRRReeeeppppoooorrrrttttiiiinnnngggg
  38.      Error messages can be generated with the iiiillllEEEErrrrrrrroooorrrr() routine. The _f_l_a_g_s
  39.      parameter can have one of the following values:
  40.  
  41.      MM_INFO        informational message, many error handlers will just
  42.                     ignore the message; this is primarily intended for
  43.                     debugging messages
  44.  
  45.      MM_WARNING     warning, most error handlers will return and allow the
  46.                     program to continue executing
  47.  
  48.      MM_ERROR       error, some error handlers will abort (the default error
  49.                     handler will)
  50.  
  51.      MM_HALT        fatal error, most error handlers will abort the program
  52.  
  53.      The _f_m_t parameter is treated as a pppprrrriiiinnnnttttffff() format string. The remaining
  54.      parameters (if any) are used in the formatting process as dictated by the
  55.      format string.
  56.  
  57.      The iiiillllEEEErrrrrrrroooorrrrVVVV() routine is provided for situations where the variable
  58.      arguments have already been packaged in the "va_list" argument, _a_p. See
  59.      the stdarg(5) man page for more details on this mechanism.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. iiiillllEEEErrrrrrrroooorrrr((((3333))))         IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll         iiiillllEEEErrrrrrrroooorrrr((((3333))))
  71.  
  72.  
  73.  
  74.    HHHHaaaannnnddddlllliiiinnnngggg EEEErrrrrrrroooorrrrssss
  75.      The handling of errors is controlled by iiiillllSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(). The error
  76.      handler is specified by the _n_e_w_h_a_n_d_l_e_r parameter and will be passed the
  77.      _n_e_w_a_r_g parameter as a user closure.  The prototype for an error handling
  78.      routine that could be passed as _n_e_w_h_a_n_d_l_e_r is:
  79.  
  80.           handler(void* closureArg, int flags, const char* fmt, va_list ap)
  81.  
  82.      where the _c_l_o_s_u_r_e_A_r_g corresponds to the _n_e_w_a_r_g parameter of
  83.      iiiillllSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr() and the _f_l_a_g_s, _f_m_t and _a_p parameters are as described
  84.      for _i_l_E_r_r_o_r_V().
  85.  
  86.      It is up to the error handler to decide whether or not to output a
  87.      message and whether or not to abort based on the value of _f_l_a_g_s.
  88.  
  89.      The user may choose to supply their own error handler or use one of three
  90.      built-in error handlers supplied with IL:
  91.  
  92.      ilNaiveErrorHandler     this handler will abort on errors or fatal
  93.                              errors, it ignores informational messages; this
  94.                              is the default handler
  95.  
  96.      ilRobustErrorHandler    this handler will only abort on fatal errors, it
  97.                              ignores informational messages
  98.  
  99.      ilSilentErrorHandler    this handler will ignore all but fatal errors,
  100.                              which will be printed and cause the program to
  101.                              exit.
  102.  
  103.    TTTTrrrraaaannnnssssllllaaaattttiiiinnnngggg EEEErrrrrrrroooorrrr SSSSttttaaaattttuuuussss CCCCooooddddeeeessss
  104.      Errors are encoded via the ilStatus type.  There are three components of
  105.      an ilStatus code:
  106.  
  107.           unsigned int mainstatus:12    IL status code
  108.  
  109.           unsigned int subDomain:4      domain of subStatus
  110.  
  111.           unsigned int subStatus:16     subdomain status code
  112.  
  113.      _m_a_i_n_s_t_a_t_u_s encodes a main status code; _s_u_b_S_t_a_t_u_s encodes an elaboration
  114.      of the main status code from another domain. For example: _m_a_i_n_s_t_a_t_u_s
  115.      might be ilOPENFAILED and _s_u_b_S_t_a_t_u_s might be ENOFILE to indicate why IL
  116.      returned ilOPENFAILED. In order to determine what _s_u_b_S_t_a_t_u_s means one
  117.      must examine _s_u_b_d_o_m_a_i_n to see whether _s_u_b_S_t_a_t_u_s contains UNIX errno's,
  118.      etc.
  119.  
  120.      The completely 0 status code, ilOKAY, is reserved.  This makes it easier
  121.      for most cases in which the caller does not care about the specific
  122.      value, but only wants to compare with ilOKAY.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. iiiillllEEEErrrrrrrroooorrrr((((3333))))         IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll         iiiillllEEEErrrrrrrroooorrrr((((3333))))
  137.  
  138.  
  139.  
  140.      These fields of the ilStatus type can be picked apart with the
  141.      iiiillllGGGGeeeettttMMMMaaaaiiiinnnnSSSSttttaaaattttuuuussss(), iiiillllGGGGeeeettttSSSSuuuubbbbDDDDoooommmmaaaaiiiinnnn() and iiiillllGGGGeeeettttSSSSuuuubbbbSSSSttttaaaattttuuuussss() macros defined
  142.      in <il/ilError.h>.
  143.  
  144.      The ilMainStatus enumerated type used for IL generated errors can be
  145.      translated to a string using the iiiillllMMMMaaaaiiiinnnnSSSSttttaaaattttuuuussssTTTTooooSSSSttttrrrriiiinnnngggg() routine.
  146.  
  147.      An encoded ilStatus value can be converted to a string using
  148.      iiiillllSSSSttttaaaattttuuuussssTTTTooooSSSSttttrrrriiiinnnngggg().  The message will be converted into the user's
  149.      buffer, _b_u_f, and truncated to _b_u_f_s_i_z_e characters in length if necessary.
  150.  
  151.      An IFL status code can be converted to an IL status code using the
  152.      iiiillllSSSSttttaaaattttuuuussssFFFFrrrroooommmmIIIIffffllllSSSSttttaaaattttuuuussss() function.
  153.  
  154.      An ilMainStatus with optional sub-domain and sub-status is encoded into
  155.      an ilStatus value by using the iiiillllSSSSttttaaaattttuuuussssEEEEnnnnccccooooddddeeee() function.
  156.  
  157. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  158.      iflError(3)
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.